Appendices

6.1 Appendix A: Macromedia Director

Macromedia Director is an authoring tool that allows developers to easily create rich multimedia applications. Using Director, the developer can import multiple multimedia assets (such as 3D graphics, animations, sounds and digital video), integrate them into a single entity called a "movie," and add user interactivity to control the playing of the movie. Developers can add functionality to Director (both at movie creation and runtime) through the use of extensions known as Xtras. The completed movie is distributed to users as a self-running executable (known as Projectors). It is this projector that is the shopPBS application. Visit the Macromedia Web site (www.macromedia.com) for more information about Director.

A Director application is a "movie," and all the media used in the movie is called the "cast." Each cast member-be it a JPEG or WAV or some other type of file-has a "script" that defines the behavior of the cast member. The "score" consists of all the frames of the movie and defines how all the cast members move. The language used to program the behavior of the cast is called Lingo. An Xtra extends the capability of the movie by allowing the movie, using Lingo commands, to access additional functions, or handlers in Lingo terms. The Xtra in the InfiniteCD component allows the movie to get updated files via Marimba. It is quite simple to use an Xtra in a Director movie.

1. The Xtra that you want to use must be in one of the following locations:
   Location #1: The Xtras subdirectory, which is in the same location as the Director application.
   Location #2: The Windows\Macromed\Xtras subdirectory on Windows 3.1 or the Program Files\Common Files\Macromedia\Xtras subdirectory on Windows 95 or Windows NT*.

2. Use the show lib command to list all available Xtras.

3. Use put interface (xtra"InfiniteCD") to list all the handlers that make up the Xtra. If there is an asterisk (*) in front of the handler it means that the handler is global and can be used at any time. All the handlers in the InfiniteCD Xtra are global.

When you have finished your movie and are ready to ship it to the consumer, you will need a "projector," or an executable file of your movie. Your Xtra will need to be included with the executable, and your installation program will need to place the Xtras used by your movie in a subdirectory called "Xtras" in the same place as your runtime projector application.

6.2 Appendix B: Marimba Castanet

Castanet is a "push" technology that uses user profile information to send updated files to a client. Several parts make up the Marimba package. First is a Castanet channel, which is an application, a service or data to be distributed across the Internet or an intranet. Next is the Castanet Transmitter, network server software that manages the distribution and maintenance of Castanet channels. Last is the Castanet client, client software that monitors, receives and manages channels selected by an end user. It includes the Castanet Tuner and the Castanet UpdateNow SDK.

On the client side of the shopPBS application, the Castanet UpdateNow SDK is used to enable the UI to request updates and send profile information. On the server, the Castanet Transmitter sends the update files. A Castanet plug-in written for the InfiniteCD project is plugged into the transmitter and handles the profile information and sending profile-specific files. Castanet is channel-based, meaning that each InfiniteCD application will have at least one channel devoted to it. When shopPBS is installed, the user is subscribed to the appropriate channel. An application can use more than one channel. An InfiniteCD application for a TV network might have a "kids" section, a "comedy" section and a "drama" section. Each section may be implemented using a separate channel to get updates.

6.2.1 Castanet SDK

The Castanet UpdateNow SDK is a C DLL that is used by the ActiveX control to perform update requests. It was necessary to use this SDK because the Castanet Tuner is written in Java. The tuner could not be used by the movie to send the update requests because the security "sandbox" in the Java virtual machine prevents the updated files from being written to disk.

Before each update, the update session is initialized by using mrbInitUpdate. Then the channel directory is prepared by using mrbPrepare. The actual update is initiated by using mrbUpdate, which contacts the transmitter, using a proxy if specified, to make an update request. Then it notifies the application of the files that will be updated. It notifies the application of the update progress. It downloads the update (to a holding area). Then it installs the update to the channel directory. It builds an undo area during installation and notifies the application of installation progress. Finally, the Update control terminates the update session by using mrbTermUpdate.

Appendix C: InfiniteCD API

The following appendix describes the interfaces presented by the InfiniteCD components:

• An Update component used to update a channel and receive pushed assets.
• A NetConnect component that allows connection to the Internet (ISP) via the modem.

The interfaces are described for two classes of apps:

• ActiveX control interface for VisualBasic* and C/C++ based apps.
• Xtra interfaces for Macromedia Director based apps. The Xtra interface is built on top of the ActiveX controls.

The Update Component

This section describes the properties, methods and events provided by the InfiniteCD Update component.

Properties

Following is a list of properties associated with the InfiniteCD ActiveX control accessible via the appropriate Get/Set routines. The Set routines cause the properties to be persistent in the Windows registry, and the Get routines retrieve those properties.

RegisterApp must be called prior to calling any of the Set/Get properties. Failure to do so will return a NULL value for Get property and a no-op for Set property.

• transmitter: Specifies the IP address in raw form (e.g., 123.123.123.12:88) or name form (e.g., foobar.com) of the machine that runs the "push" server. The address must include the port ID of the proxy, unless it uses the default http port 80. It must be set prior to calling UpdateNow.

   Active X interface:
  BSTR GetTransmitter ();
  void SetTransmitter (LPCTSTR transmitter);
   Xtra interface:
   * GetTransmitter -- returns a string 
   * SetTransmitter string transmitter --
  

• proxy: Specifies the IP address in raw form (e.g., 123.123.123.12:911) or name form (e.g., proxy.foo.com:911) of the machine that serves as the http proxy. The address must include the port ID of the proxy. This must be set before calling UpdateNow only if the application is running inside a firewall and wants to access the "push" server outside the firewall.

   Active X interface:
  BSTR GetProxy ();
  afx_msg void SetProxy (LPCTSTR proxy);
   Xtra interface:
  * GetProxy -- returns a string
  * SetProxy string proxy --
  

Methods

• RegisterApp: All InfiniteCD applications must call this prior to using any Update components properties or methods. This registers the application with the "push" vendor and ensures that the Update component can access application-specific channel data in the Windows registry.

   Active X interface:
  int RegisterApp(LPCTSTR applicationName)
   Xtra interface:
  * RegisterApp string applicationName -- returns integer 
  

  Parameters:
  applicationName: Name of InfiniteCD application that updates channels. It must be the same as the applicationName used in the InstallChannel call.
  Returns:
  A positive value (greater than zero) if properly registered, a negative value if not. The application may call GetErrorMsg with the negative value to get error text.

• UpdateNow: Updates the channelName channel by connecting to the transmitter and delivering the latest assets, or otherwise modifying the assets in the channelDir directory. This method is asynchronous and will return after initiating the update. During the course of the update, the application will receive several events indicating the progress of the update and errors, if any. The update is complete upon receiving the UpdateDone event.

  UpdateNow requires that the transmitter property be set to the "push" server's address. This is either done during install via InstallChannel, or by the application using SetTransmitter.

  The name and value of the profile set using SetProfile are always sent to the server, in addition to the profile parameter.

   Active X interface:
  int UpdateNow (LPCTSTR channelName, LPCTSTR channelDir,
  LPCTSTR profile, LPCTSTR appData);
   Xtra interface:
  *  UpdateNow string channelName, string channelDir,
  string profile, string appData -- returns integer handle
  Parameters:  
  	channelName: Name of channel to update
  

  channelDir: Full pathname of directory that will contain the "pushed" assets. If NULL, then the default path set using InstallChannel will be used.
  profile: Contains user preferences. Interpreted by the "push" server to send back assets based on the profile. Pass in NULL, if no user preferences are involved. In this case, the server sends back generic updates that are applicable to all clients.
  appData: Application-supplied string that identifies this update. This parameter is passed back to the application in all the events.
  Returns:
  An opaque integer handle that represents this instance of the update. It is a positive value (greater than zero) if the update is successfully initiated, a negative value if not. Application may call GetErrorMsg with the negative value to get error text. The application may call CancelUpdate with the positive handle to abort this instance of the update.

  Events: 
  The following mandatory events will be sent in this order:
  ProgressStart,
  ProgressPercent, // several of these
  UpdateInstalling,
  UpdateDone
         At any point the following events may be optionally sent:
  	UpdateError,
  	GenericMsg.
  

• CancelUpdate: Aborts the specified update, if one is in progress. If not, it's a no-op. This method is synchronous.

   Active X interface:
  	int CancelUpdate (int updateHandle);
   Xtra interface:
  * CancelUpdate -- returns integer
  

  Parameters:
  updateHandle: The positive valued handle returned by UpdateNow. This handle identifies a particular instance of update.
  Returns:
  A positive value (greater than zero) if successful, a negative value if not. Application may call GetErrorMsg with the negative value to get error text.

• GetErrorMsg: Returns an error string of the given error code. This should be called soon after one of the methods returns an error condition (i.e., a negative value).

   Active X interface:
  BSTR GetErrorMsg (int error);
   Xtra interface:
  * GetErrorMsg int error -- returns a string
  

  Parameters:
  error: The negative-valued handle returned by any of the above methods.
  Returns: Unicode String with the error text.

• InstallChannel: This is the primary interface between the InfiniteCD applications and the Intel Channel Selector application. Stores the parameters in the Windows registry for use by the Intel Channel Selector. It is intended for the Install app. Can be called multiple times to install several channels.

   Active X interface:
  int InstallChannel(
  LPCTSTR channelName, LPCTSTR channelDirectory, LPCTSTR channelTransmitter,
  LPCTSTR channelLogoPath, LPCTSTR applicationPath, LPCTSTR applicationName,
  BOOL hidden)
  Xtra interface:
  None
  

  Parameters:
  channelName: Name of channel to update.
  channelDirectory: Full pathname of the directory that will contain the channel's "pushed" assets.
  channelTransmitter: Specifies the IP address in raw form (e.g., 123.123.123.12:88) or name form (e.g., foobar.com) of the machine that runs the "push" server. The address must include the port ID of the proxy, unless it uses the default http port 80.
  channelLogoPath: Full pathname of a graphic logo file. Format of the logo is 80x32 pixels in Windows BMP format. applicationPath: Full pathname of the application using the Update control.
  applicationName: Name of application updating the channels. Must be the same as the appName used in the RegisterApp call.
  hidden: Set by an application to TRUE, if it did not want to be displayed in the Channel Selector, or updated by the Channel Selector. Default value is FALSE.

  	// This parameter is currently ignored.
  Returns: 
  A positive value (greater than zero) if successful, a negative value if not. 
  

• UnInstallChannel: Clears the Windows registry entries associated with the channel. This is primarily intended for the UnInstall app and not for the rest of the InfiniteCD apps.

   Active X interface:
  int UnInstallChannel(LPCTSTR channelName,
  LPCTSTR applicationName);
  Xtra interface: 
  None.
  

  Parameters: channelName: Name of channel to uninstall.
  applicationName: Name of application updating the channels. Must be the same as the appName used in the RegisterApp and InstallChannel call.
  Returns:
  A positive value (greater than zero) if successful, a negative value if not.

• ProgressStart: Fired to give the application an opportunity to set up for progress events.

   Active X interface:
  ProgressStart (LPCTSTR appData);
   Xtra interface:
  * SetProgressStartHandler string handlerString --
  sets the handler you define for callback 
  

• ProgressPercent: Fired to indicate the extent of the progress. Application will receive numerous ProgressPercent events with monotonically increasing percent.

   Active X interface:
  ProgressPercent (short percent, LPCTSTR appData);
   Xtra interface:
  * SetProgressPercentHandler  string handlerString --
  handler called back with a short
  parameter percent
  

• UpdateInstalling: Fired to indicate that the assets have been received in a holding area and are about to be installed in channelDir. App should not access files in channelDir between UpdateInstalling and UpdateDone.

   Active X interface:
  UpdateInstalling (LPCTSTR appData);
   Xtra interface:
  * SetUpdateInstallingHandler string handlerString --
  sets the handler you define for callback
  

• UpdateDone: Fired to indicate that the entire update, including the install to channelDir is complete.

     Active X interface:
  UpdateDone (LPCTSTR appData);
   Xtra interface:
  * SetUpdateDoneHandler string handlerString --
  sets the handler you define for callback
  

• UpdateError: Fired to indicate error. The errorText parameter is the full text of the error. The error parameter is for only those applications that want to provide their own error message text. Most applications will use the provided errorText to display an error message to the user.

   Active X interface:
  UpdateError (int error, LPCTSTR errorText, LPCTSTR appData);
   Xtra interface:
  * SetUpdateErrorHandler string handlerString -- sets the handler you define
  for callback with the error code and appData as parameters
  

• GenericMsg: Fired to indicate several messages from the push vendor's client. Applications may use this to debug or simply log the messages.

   Active X interface:
  GenericMsg (LPCTSTR  txt, LPCTSTR appData);
   Xtra interface:
  * SetGenericMsgHandler string handlerString -- sets the handler you define
  for callback with a msg string and appData as parameters
  

This section describes the properties, methods and events provided by the InfiniteCD NetConnect component. This component is used to connect users to their Internet Service Provider (ISP) via modem.

Properties
None

Methods

• Connect: Establishes a transparent dial-up connection between the client PC and dial-up server, thus allowing the user to get onto the Internet. This method is asynchronous and will return after initiating the connection. During the course of the connection, the application will receive several events indicating the progress of the dial-up connection and errors, if any. The connection is complete upon receiving the Connected event.

  NOTE: It is not required for an app to call Connect for a dial-up connection. In the absence of an Internet connection, if an app calls UpdateNow, the Windows 95 Dial-up Networking standard ConnectTo dialog box pops up and enables the user to proceed with the dial-up connection. This Connect, on the other hand, provides an unattended, transparent dial-up connection without user intervention.

   Active X interface:
  	int Connect (LPCTSTR  server);
   Xtra interface:
  * Connect string server -- returns integer
  

  Parameters:
  server: Name of dial-up server to connect to. This is typically the name of one of the Dial-up icons in the Dial-up Networking folder. If this parameter is NULL, the routine will use the default dial-up icon set up by the user in Control Panel, Internet. If no default is set and the parameter is NULL, the routine errors out.
  Returns:
  A positive value (greater than zero) if successful, a negative value if not. Application may call GetErrorMsg with the negative value to get error text.

  Events:  The following events will be sent in this order:
  	ConnectProgress // several of these
  	Connected
  	At any point the following event may be optionally sent:
  	ConnectError
  

• Disconnect: Disconnects the currently existing dial-up connection to the Internet. If a connection does not exist, this routine is a no-op. If the user's preferred connection to the Internet is via the LAN, this routine does nothing.

   
   Active X interface:
  	int Disconnect ();
   Xtra interface:
  * Disconnect -- returns integer
  

  Parameters: None
  Returns:
  A positive value (greater than zero) if successful, a negative value if not. Application may call GetErrorMsg with the negative value to get error text.

• IsConnected: Indicates if the client PC has a dial-up connection to the Internet.

   Active X interface:
  	int IsConnected ();
   Xtra interface:
  * IsConnected -- returns integer
  

  Parameters: None
  Returns:
  The value 0 if there is no dial-up connection to the Internet, 1 if a dial-up connection has been successfully established, and 2 if a dial-up connection is in progress. If the user is connected to the Internet directly (via a LAN), this will return 0.

• GetErrorMsg: Returns an error string of the given error code. This should be called soon after one of the methods returns an error condition (i.e., a negative value).

   Active X interface:
  BSTR GetErrorMsg (error);
   Xtra interface:
  * GetErrorMsg -- returns a string
  
  

  Parameters:
  error: The negative-valued handle returned by any of the above methods.
  Returns: Unicode String with the error text.

• ConnectProgress: Fired to indicate connection progress. Application will receive numerous events with different progress strings.

   Active X interface:
  ConnectProgress (LPCTSTR progress);
   Xtra interface:
  * Set ConnectProgressHandler string handlerString -
  handler called back with a string
  parameter percent
  

• Connected: Fired to indicate successful completion of connection.

   
   Active X interface:
  Connected ();
   Xtra interface:
  * SetConnectedHandler --
  sets the handler you define for callback
  

• Disconnected: Fired to indicate successful completion of disconnection.

   Active X interface:
  Disconnected ();
   Xtra interface:
  * SetDisconnectedHandler --
  sets the handler you define for callback
  

• ConnectError: Fired to indicate error. The application may call GetErrorMsg with the error code to get the text of the error message.

   Active X interface:
  ConnectError (int error);
   Xtra interface:
  * SetConnectErrorHandler string handlerString --
  sets the handler you define
  for callback with the error text as parameter
  

6.4 References

6.4.1 Books

Writing Castanet Plug-ins
Official Marimba Guide to Castanet Laura Lemay Published by Sams.Net

For additional information about the following topics, visit these Web sites.

InfiniteCD and Hybrid Applications www.intel.com/drg

Marimba Castanet www.marimba.com

ActiveX Controls www.activex.com

Macromedia Director www.macromedia.com

WebXtra Director Xtra www.tbaiana.com

PBS Online www.pbs.org